home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / olrdrs / qwkndt1a.zip / FOSSIL.DOC < prev    next >
Text File  |  1988-02-11  |  35KB  |  832 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                  Fundamentals of FOSSIL implementation and use
  14.                         Version 5,  February 11,  1988
  15.                        Rick Moore,  Solar Wind Computing
  16.  
  17.  
  18.           FidoNet Address: Zone 1,  Network 115,  Node 333 (1:115/333)
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  Copyright (C) 1987, VEP Software, Naugatuck, CT 06770. All rights reserved.
  48.  Copyright (C) 1988, Rick Moore,  Homewood,  IL, 60430. All rights reserved.
  49.  
  50.  This document may be freely used or copied by anyone interested in the data
  51.  contained herein. No fees may be charged for distribution of this document.
  52.  You will be held  accountable for all such charges,  and expected to either
  53.  reimburse those persons or organizations so charged,  or to make a donation
  54.  in the exact amount of those fees to the International FidoNet Association,
  55.  to  assist  them in their  efforts to  advance the  technology of  personal
  56.  computer telecommunications.
  57.  
  58. Fundamentals of FOSSIL implementation and use                         Page 2
  59. Introduction
  60.  
  61.  
  62.  
  63.  A. Objectives of this document
  64.  
  65.     This document is directed at implementors or intellectuals.  It is meant
  66.     for use in implementing applications that can use FOSSIL drivers, or for
  67.     details needed to implement a new FOSSIL. As such it won't always go out
  68.     of its way to explain itself to the neophyte.
  69.  
  70.     This document will have served its purpose to you if you are able to use
  71.     the data contained within to perform either of the above tasks.   If you
  72.     feel  that necessary  data has  been omitted  please contact  Rick Moore
  73.     at the above listed address so that the  appropriate changes can be made.
  74.     Any lines changed in the current version are marked with "|" in the left
  75.     margin.
  76.  
  77.  
  78.  B. Historical perspective
  79.  
  80.     For those people who were not lucky enough to have an IBM PC or a system
  81.     nearly completely compatible, the world has not been very friendly. With
  82.     his implementation of the Generic Fido(tm) driver,  Tom Jennings made it
  83.     possible for systems that had nothing in common with an IBM PC except an
  84.     808x-class processor, and the ability to run MS-DOS Version 2 and above,
  85.     to run his Fido(tm) software. That was a lot to ask, and a lot of people
  86.     thought it was enough.
  87.  
  88.     But not everyone.  While Thom Henderson was debugging Version 4.0 of his
  89.     SEAdog(tm) mail package,  an "extended" Generic driver was designed  (in
  90.     cooperation with Bob Hartman)   as a quick kludge to help him get past a
  91.     problem with certain UART chips.The new hook was quickly pounced upon by
  92.     Vince Perriello,  who, with almost DAILY prodding (ouch! it still hurts)
  93.     by Ken Kaplan,had been working with Henderson to get DEC Rainbow support
  94.     into SEAdog. Vince then coded a driver to use this hook and - Voila! -
  95.     SEAdog 4.0 started working like a champ on the Rainbow.
  96.  
  97.     At the same time something was rotten in the state of Texas. Wynn Wagner
  98.     started  encountering some serious  difficulties in his Opus development
  99.     effort. Specifically, he couldn't force the Greenleaf(tm) Communications
  100.     Libraries to behave in exactly the way he felt Opus required.  Enter Bob
  101.     Hartman.Having already enjoyed success in the effort with Thom Henderson,
  102.     he suggested to Wynn that with very few extensions,  any driver that was
  103.     already  SEAdog(tm) 4.0 compatible could drive Opus as well.  About that
  104.     time, Vince called Wynn to discuss porting Opus to the DEC Rainbow. Wynn
  105.     called Bob, Bob called Vince, and the FOSSIL driver came into existence.
  106.  
  107.     FOSSIL is an acronym for "Fido/Opus/SEAdog Standard Interface Layer". To
  108.     say that the concept has gained wide acceptance in the FidoNet community
  109.     would be an understatement. Henk Wevers' DUTCHIE package uses the FOSSIL
  110.     communications services.   Ron Bemis' OUTER package uses FOSSIL services
  111.     for everything it does and as a result it is completely generic.   There
  112.     are already FOSSIL implementations for the Tandy 2000, Heath/Zenith 100,
  113.     Sanyo 555 and other "non-IBM" architectures. With each new 'port' of the
  114.     spec, the potential of a properly coded FOSSIL application grows!
  115.  
  116. Fundamentals of FOSSIL implementation and use                         Page 3
  117. Basic conventions and calling method
  118.  
  119.  
  120.  
  121.  C. Basic principles of a FOSSIL driver
  122.  
  123.     1)  Interrupt 14h.
  124.  
  125.     The one basic rule that the driver depends upon,  is the ability for ANY
  126.     target machine to allow the vector for INT 14h (usually pointing to BIOS
  127.     comm functions) to be "stolen" by the driver.  In a system where the INT
  128.     14h vector is used already, it must be possible to replace the "builtin"
  129.     functionality with that of a FOSSIL,  when an application that wants the
  130.     use of a FOSSIL is to be run on the target machine.
  131.  
  132.  
  133.     2)  How to install a FOSSIL driver in a system
  134.  
  135.     There's no hard and fast way to do this. The FOSSIL might be implemented
  136.     as part of a device driver (like Ray Gwinn's X00.SYS) and therefore gets
  137.     loaded using a line in CONFIG.SYS at bootup time.  It might be done as a
  138.     TSR (terminate and stay resident) program, in which event you install it
  139.     by running the program  (DECcomm by Vince Perriello and Opus!Comm by Bob
  140.     Hartman work this way, for example).
  141.  
  142.  
  143.     3)  How an application can detect the presence of a FOSSIL
  144.  
  145.     The driver has a "signature" that can be used to determine whether it is
  146.     present in memory. At offset 6 in the INT 14h service routine is a word,
  147.     1954h,  followed  by a  byte that  specifies the maximum function number
  148.     supported by the driver. This is to make it possible to determine when a
  149.     driver is present and what level of functionality it provides. Also, the
  150.     Init call (see below)  returns a 1954h  in AX.  SEAdog(tm)  looks at the
  151.     signature and Opus just goes for the Init. Fido doesn't do either.
  152.  
  153.  
  154.     4)  How to call a FOSSIL function
  155.  
  156.     The FOSSIL driver  is entered  by issuing  a software Interrupt 14h from
  157.     the application  program. The code corresponding to the desired function
  158.     should be in 8-bit register AH. For calls that relate to communications,
  159.     the port number will be passed from the application in register DX. When
  160.     DX contains a zero (0) it signifies use of COM1, or whatever the "first"
  161.     serial port on your machine is called. A one (1) in DX points the driver
  162.     at COM2, and so on.  A value of 00FFh in DX is considered a special case
  163.     where the driver  should do no actual processing but return SUCCESS.  In
  164.     the specific case of Init/Uninit with DX=00FFh,the FOSSIL should perform
  165.     all non-communications  processing  necessary  with such calls.  In some
  166.     machines  (H/Z-100 for example),  the FOSSIL must  assume control of the
  167.     keyboard in order to service the keyboard functions.
  168.  
  169.     FOR ALL FUNCTIONS,  ALL REGISTERS NOT SPECIFICALLY CONTAINING A FUNCTION
  170.     RETURN VALUE MUST BE PRESERVED ACROSS THE CALL.
  171.  
  172. Fundamentals of FOSSIL implementation and use                         Page 4
  173. Communications functions
  174.  
  175.  
  176. D. Functions currently defined for FOSSILs
  177.  
  178.  
  179.     AH = 00h    Set baud rate
  180.  
  181.             Parameters:
  182.                 Entry:  AL = Baud rate code
  183.                         DX = Port number
  184. |               Exit:   AX = Port status (see function 03h)
  185.  
  186.     This works the same as the  equivalent IBM PC BIOS call,  except that it
  187.     ONLY selects a baud rate.  This is passed in the high order 3 bits of AL
  188.     as follows:
  189.  
  190.                 010 =   300 baud
  191.                 011 =   600  ''
  192.                 100 =  1200  ''
  193.                 101 =  2400  ''
  194.                 110 =  4800  ''
  195.                 111 =  9600  ''
  196.                 000 = 19200  '' (Replaces old 110 baud mask)
  197.                 001 = 38400  '' (Replaces old 150 baud mask)
  198.  
  199.     The low order 5 bits can be implemented or not by the FOSSIL, but in all
  200.     cases, if the low order bits of AL are 00011,  the result should be that
  201.     the communications device should be set to eight da